LESSON 5
CUSTOM WRITE PATTERN
Version 5.0.01

The example below shows how to write a "normal" pattern using a direct Z80 subroutine call (no UPI required, no UPI processing delay). A normal write is defined as a write not utilizing the magic expand, flop or rotator function. You can write a pattern in one of three ways when using a normal magic write. The Magic Register, bits 5 and 4, indicates which normal magic write is to be utilized by the magic hardware. The table below shows the set up for the Magic Register for the indicated magic write.

Type of	Magic Register
write		bit 5    bit 4

plop		  0	     0

XOR		  1	     0

OR		  0	     1

This particular pattern write subroutine listed below is a copy of the magic pattern write labeled MWRT, which is located in the Bally/Astrocade ROM. See the NM ROM code listing on page 50, address 0725H (cross stmt 2241).

Important Programming Note!

Because there are 3 versions of ROM, any program outside of the on-board ROM should NOT make direct calls or jumps to this ROM.

EXAMPLE  5-1

Program Description

Write a solid green reference byte at 4014H.
Plop write a plane pattern beginning at address 4064H (initial magic address 0064H), which is two screen RAM lines below the green reference byte.
Use standard MLM colors for this program.
Plop write the pattern.

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Example Program 5-1

PGM	4E10H	C3 33 4E	JP PGM1	Jump to main program

      PLANE PATTERN
      3 bytes wide, 5 lines high
      pixel 10 = color reg 6 = red
      pixel 01 = color reg 5 = wht
      pixel 00 = color reg 4 = blk = +

					 pixel colors	 color labels	  color
PLANE	4E13H 40 00 00 		5+++ ++++ ++++	            	  label
		50 15 00		55++ +555 ++++	6 =red=pixel 10	  example
		55 55 54		5555 5555 555+	5 =wht=pixel 01	  byte 40
		55 AA 55		5555 6666 5555    + =blk=pixel 00	  0100 0000
	4E1FH	15 55 54		+555 5555 555+				  5 +  + +

	WRITE PATTERN
	Enter With:
	HL = Pattern Address
	 B = Y Pattern Size (Lines High)
	 C = X Pattern Size (Bytes Wide)
	DE = Initial Magic Address For Pattern Write
	     (upper left magic address of normal pattern write)

WPAT	4E22H AF		XOR A		zero A
WPAT1		C5		PUSH BC	save YSIZE, XSIZE
		D5		PUSH DE	save magic adr (1st adr in line)
	4E25H	47		LD B,A	B=0
		ED B0		LDIR		write a line
						(DE) <-- (HL)
						INC DE
						INC HL
						DEC BC
						Loop back if BC is not 0
		12		LD (DE),A	clear final byte in line
						for any shift at end of line
		D1		POP DE	get initial line magic address
		EB		EX DE,HL	put that address in HL
		0E 28		LD C,28H	C = bytes per line = 40
		09		ADD HL,BC	point HL at magic address of next line
		EB		EX DE,HL	DE = magic address of next line
						HL = pattern address of next line
		C1		POP BC	put YSIZE, XSIZE back in BC
	4E30H	10 F1		DJNZ WPAT1	Loop back 15 bytes to write next line
						15  = 0000 1111
						cpl = 1111 0000
						+1  = _______+1
						    = 1111 0001
							  F    1
						jump back code = F1H
	4E32H	C9		RET		finished pattern write
						return to PGM2
	MAIN PROGRAM

PGM1	4E33H	CD 47 23	CALL CLEAR	call MLM CLEAR screen sub

	WRITE REFERENCE BYTE

	4E36H	3E FF		LD A,FFH	  A = color value = solid green
	4E38H	32 14 40	LD (4014H),A  write the reference byte

	SET UP MAGIC REGISTER

	4E3BH	3E 00		LD A,MREG      A = magic register request,
						   begin with zero shift, plop write
		D3 0C		OUT (MAGIC),A  set up magic function request
						   output request to magic reg port 0CH
	SET UP PATTERN WRITE

		21 13 4E	LD HL,PLANE	   point HL at pattern address
	4E42H	01 03 05	LD BC,0503H	   B = YSIZE = 5 lines high
						   C = XSIZE = 3 bytes wide
	4E45H	11 64 00	LD DE,0064H	   DE = initial magic address

	WRITE THE PATTERN

	4E48H	00 00		NOPs		  [leave room for Lesson 6
		00 00		NOPs		  to flop the pattern]
		CD 22 4E	CALL WPAT	  write the plane
PGM2	4E4FH	C9		RET		  return to MLM

+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

Beginner Exercises

1. Try shifting the plane to the right 1,2 or 3 pixels by entering into the program at the address 4E3CH, the byte 01,02 or 03H respectively.

2. Try writing a plane at a different location on the screen, for example, using magic addresses 0000H or 0025H which write the plane at the upper left or right corners of the screen RAM area. Reference the screen map in the NM system description, page 86. If you shift the plane 1,2 or 3 pixels to the right at magic address 0025H, then the front of the plane will wrap around the left side of the screen RAM area, but at one screen RAM line lower. If you study the pattern write subroutine, focusing on how one line is written, you should be able to determine why this pattern wrap around occurs. The magic address for the plane written must be entered in the program at 4E46 and 4E47H, in a swapped format (address low order byte first, followed by the address high order byte).

3. Try working the XOR logical magic function, bit 5 in the Magic Register. See if you can write and blank the plane using the XOR logical magic function. Use MLM to call the program at address 4E36H (instead of 4E10H) so you won't clear the screen when you try to blank the plane.

4. Try writing the solid green reference byte at 4064H, which is two screen RAM lines below 4014H. Then, write the plane using the magic OR logical function, bit 4 in the Magic Register. Don't forget to reset bit 5 in the Magic Register to zero. Write the plane at magic address 0012,0013 or 0014H which will visually look like the plane is flying behind the solid green reference byte.

End of LESSON 5 document
Custom Write Pattern
MCM Design
Aug 2019